diff options
Diffstat (limited to 'doc/lispref/loading.texi')
| -rw-r--r-- | doc/lispref/loading.texi | 120 |
1 files changed, 74 insertions, 46 deletions
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 18c22142fee..8a2bb5fa2db 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -291,29 +291,35 @@ a directory) or @code{nil} (which stands for the current working directory). @end defvar - When Emacs starts up, it sets up the value of @code{load-path} -in several steps. First, it initializes @code{load-path} using -default locations set when Emacs was compiled. Normally, this -is a directory something like + When Emacs starts up, it sets up the value of @code{load-path} in +several steps. First, it looks for the directory containing its own +Lisp files, using default locations set when Emacs was compiled. It +saves this directory in @code{lisp-directory}. Normally, this is a +directory where the @file{*.elc} files are installed, something like @example "/usr/local/share/emacs/@var{version}/lisp" @end example -(In this and the following examples, replace @file{/usr/local} with -the installation prefix appropriate for your Emacs.) -These directories contain the standard Lisp files that come with -Emacs. If Emacs cannot find them, it will not start correctly. +@noindent +where @var{version} is the Emacs version. (In this and the following +examples, replace @file{/usr/local} with the prefix appropriate for +your Emacs installation.) This directory and its subdirectories +contain the standard Lisp files that come with Emacs. If Emacs cannot +find its own Lisp files, it will not start correctly. If you run Emacs from the directory where it was built---that is, an -executable that has not been formally installed---Emacs instead -initializes @code{load-path} using the @file{lisp} -directory in the directory containing the sources from which it -was built. +executable that has not been installed yet---Emacs instead initializes +@code{lisp-directory} using the @file{lisp} subdirectory of the +directory containing the sources from which it was built. + +Emacs then initializes @code{load-path} with this @code{lisp-directory}. @c Though there should be no *.el files in builddir/lisp, so it's pointless. If you built Emacs in a separate directory from the -sources, it also adds the lisp directories from the build directory. -(In all cases, elements are represented as absolute file names.) +sources, it also adds the @file{lisp} subdirectory of the build directory. + +All of these directories are stored in the above two variables as +absolute file names. @cindex site-lisp directories Unless you start Emacs with the @option{--no-site-lisp} option, @@ -333,12 +339,12 @@ and @end example @noindent -The first one is for locally installed files for a specific Emacs -version; the second is for locally installed files meant for use -with all installed Emacs versions. (If Emacs is running uninstalled, -it also adds @file{site-lisp} directories from the source and build -directories, if they exist. Normally these directories do not contain -@file{site-lisp} directories.) +The first one is for locally installed files for the current Emacs +@var{version}; the second is for locally installed files meant for use +with any installed Emacs version. (If Emacs is running uninstalled, +it also adds @file{site-lisp} subdirectories from the source and build +directories, if they exist. However, normally the source and build +directories do not contain @file{site-lisp} subdirectories.) @cindex @env{EMACSLOADPATH} environment variable If the environment variable @env{EMACSLOADPATH} is set, it modifies @@ -360,9 +366,10 @@ export EMACSLOADPATH=/home/foo/.emacs.d/lisp: @end example An empty element in the value of the environment variable, whether -trailing (as in the above example), leading, or embedded, is replaced -by the default value of @code{load-path} as determined by the standard -initialization procedure. If there are no such empty elements, then +trailing (as in the above example, note the trailing @samp{:}), +leading, or embedded, is replaced by the default value of +@code{load-path} as determined by the standard initialization +procedure. If there are no such empty elements, then @env{EMACSLOADPATH} specifies the entire @code{load-path}. You must include either an empty element, or the explicit path to the directory containing the standard Lisp files, else Emacs will not function. @@ -391,11 +398,23 @@ add one or more directories to @code{load-path}. For example: (push "~/.emacs.d/lisp" load-path) @end example +@noindent +@xref{List Variables, push}, for the description of @code{push}. + Dumping Emacs uses a special value of @code{load-path}. If you use a @file{site-load.el} or @file{site-init.el} file to customize the dumped Emacs (@pxref{Building Emacs}), any changes to @code{load-path} that these files make will be lost after dumping. +@defvar lisp-directory +This variable holds a string naming the directory which holds +Emacs's own @file{*.el} and @file{*.elc} files. This is usually the +place where those files are located in the Emacs installation tree, +unless Emacs is run from its build directory in which case it points +to the @file{lisp} subdirectory in the source directory from which +Emacs was built. +@end defvar + @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 @@ -482,7 +501,7 @@ 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 +unibyte. This can matter when making key bindings to non-@acronym{ASCII} characters written as @code{?v@var{literal}}. @node Autoload @@ -510,7 +529,7 @@ 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. These comments do nothing on their own, but they serve as a guide for the command -@code{update-file-autoloads}, which constructs calls to @code{autoload} +@code{loaddefs-generate}, which constructs calls to @code{autoload} and arranges to execute them when Emacs is built. @defun autoload function filename &optional docstring interactive type @@ -552,7 +571,7 @@ 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 +and calls @code{keymap-set}; not even if the variable name is the same symbol @var{function}. @cindex function cell in autoload @@ -608,22 +627,19 @@ subroutines not loaded successfully because they come later in the file. macro, then an error is signaled with data @code{"Autoloading failed to define function @var{function-name}"}. -@findex update-file-autoloads -@findex make-directory-autoloads +@findex loaddefs-generate @cindex magic autoload comment @cindex autoload cookie @anchor{autoload cookie} A magic autoload comment (often called an @dfn{autoload cookie}) consists of @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} +autoloadable source file. The function @code{loaddefs-generate} writes a corresponding @code{autoload} call into @file{loaddefs.el}. (The string that serves as the autoload cookie and the name of the -file generated by @code{update-file-autoloads} can be changed from the +file generated by @code{loaddefs-generate} can be changed from the above defaults, see below.) Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}. -@kbd{M-x make-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}. The form following the magic comment is copied @@ -656,7 +672,7 @@ and @code{define-global-minor-mode}. @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 +@code{loaddefs-generate} copies it to @file{loaddefs.el}, where it is executed while building Emacs. The following example shows how @code{doctor} is prepared for @@ -709,11 +725,11 @@ corresponding autoload calls written into a file whose name is different from the default @file{loaddefs.el}. Emacs provides two variables to control this: -@defvar generate-autoload-cookie -The value of this variable should be a string whose syntax is a Lisp -comment. @kbd{M-x update-file-autoloads} copies the Lisp form that -follows the cookie into the autoload file it generates. The default -value of this variable is @code{";;;###autoload"}. +@defvar lisp-mode-autoload-regexp +The value of this constant is a regexp that matches autoload cookies. +@code{loaddefs-generate} copies the Lisp form that follows the +cookie into the autoload file it generates. This will match comments +like like @samp{;;;###autoload} and @samp{;;;###calc-autoload}. @end defvar @defvar generated-autoload-file @@ -750,7 +766,7 @@ contain definitions matching the prefix being completed. The variable @code{definition-prefixes} holds a hashtable which maps a prefix to the corresponding list of files to load for it. Entries to this mapping are added by calls to @code{register-definition-prefixes} -which are generated by @code{update-file-autoloads} +which are generated by @code{loaddefs-generate} (@pxref{Autoload}). Files which don't contain any definitions worth loading (test files, for examples), should set @code{autoload-compute-prefixes} to @code{nil} as a file-local @@ -1048,13 +1064,8 @@ list elements have these forms: The symbol @var{var} was defined as a variable. @item (defun . @var{fun}) The function @var{fun} was defined. -@item (t . @var{fun}) -The function @var{fun} was previously an autoload before this library -redefined it as a function. The following element is always @code{(defun . @var{fun})}, which represents defining @var{fun} as a function. -@item (autoload . @var{fun}) -The function @var{fun} was defined as an autoload. @item (defface . @var{face}) The face @var{face} was defined. @item (require . @var{feature}) @@ -1077,6 +1088,23 @@ The value of @code{load-history} may have one element whose @sc{car} is by adding the symbols defined to the element for the file being visited, rather than replacing that element. @xref{Eval}. +@kindex function-history @r{(function symbol property)} +In addition to @code{load-history}, every function keeps track of its +own history in the symbol property @code{function-history}. +The reason why functions are treated specially in this respect is that +it is common for functions to be defined in two steps in two different +files (typically, one of them is an autoload), so in order to be +able to properly @emph{unload} a file, we need to know more precisely +what that file did to the function definition. + +The symbol property @code{function-history} holds a list of the form +@w{@code{(@var{file1} @var{def2} @var{file2} @var{def3} ...)}}, where +@var{file1} is the last file that changed the definition and +@var{def2} was the definition before @var{file1}, set by @var{file2}, +etc. Logically this list should end with the name of the first file +that defined this function, but to save space this last element +is usually omitted. + @node Unloading @section Unloading @cindex unloading packages @@ -1091,7 +1119,7 @@ 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.) +(Loading saves these in the @code{function-history} property of the symbol.) Before restoring the previous definitions, @code{unload-feature} runs @code{remove-hook} to remove functions defined by the library from certain @@ -1156,7 +1184,7 @@ You don't need to give a directory or extension in the file name @var{library}. Normally, you just give a bare file name, like this: @example -(with-eval-after-load "js" (define-key js-mode-map "\C-c\C-c" 'js-eval)) +(with-eval-after-load "js" (keymap-set js-mode-map "C-c C-c" 'js-eval)) @end example To restrict which files can trigger the evaluation, include a |