X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/929aeac608c271b2448dffec29aeea85c69d6bff..2abc85e:/doc/lispref/loading.texi diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 51a060bc6c..d2d38d7fb5 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Loading @@ -29,6 +29,16 @@ into a buffer and evaluated there. (Indeed, most code is tested this way.) Most often, the forms are function definitions and variable definitions. + Emacs can also load compiled dynamic modules: shared libraries that +provide additional functionality for use in Emacs Lisp programs, just +like a package written in Emacs Lisp would. When a dynamic module is +loaded, Emacs calls a specially-named initialization function which +the module needs to implement, and which exposes the additional +functions and variables to Emacs Lisp programs. + +For on-demand loading of external libraries which are known in advance +to be required by certain Emacs primitives, @pxref{Dynamic Libraries}. + @menu * How Programs Do Loading:: The @code{load} function and others. * Load Suffixes:: Details about the suffixes that @code{load} tries. @@ -38,9 +48,10 @@ definitions. * Repeated Loading:: Precautions about loading a file twice. * Named Features:: Loading a library if it isn't already loaded. * Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to "unload" a library that was loaded. +* Unloading:: How to unload a library that was loaded. * Hooks for Loading:: Providing code to be run when particular libraries are loaded. +* Dynamic Modules:: Modules provide additional Lisp primitives. @end menu @node How Programs Do Loading @@ -62,19 +73,22 @@ To find the file, @code{load} first looks for a file named @var{filename} with the extension @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.) +file exists, it is loaded. If Emacs was compiled with support for +dynamic modules (@pxref{Dynamic Modules}), @code{load} next looks for +a file named @file{@var{filename}.@var{ext}}, where @var{ext} is a +system-dependent file-name extension of shared libraries. 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 Auto Compression mode is enabled, as it is by default, then if @code{load} can not find a file, it searches for a compressed version of the file before trying other file names. It decompresses and loads it if it exists. It looks for compressed versions by appending each of the suffixes in @code{jka-compr-load-suffixes} to the file name. -The value of this variable must be a list of strings. Its standard +The value of this variable must be a list of strings. Its standard value is @code{(".gz")}. If the optional argument @var{nosuffix} is non-@code{nil}, then @@ -89,7 +103,12 @@ 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 @samp{.el} or @samp{.elc} (possibly extended with a compression -suffix), unless it contains an explicit directory name. +suffix) or the shared-library extension, unless it contains an +explicit directory name. + +If the option @code{load-prefer-newer} is non-@code{nil}, then when +searching suffixes, @code{load} selects whichever version of a file +(@samp{.elc}, @samp{.el}, etc.)@: has been modified most recently. 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 @@ -187,8 +206,8 @@ 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}. +By default, this variable's value is @code{read}. @xref{Input +Functions}. Instead of using this variable, it is cleaner to use another, newer feature: to pass the function as the @var{read-function} argument to @@ -244,6 +263,12 @@ value of @code{(get-load-suffixes)} and then those in it skips the former group, and if @var{must-suffix} is non-@code{nil}, it skips the latter group. +@defopt load-prefer-newer +If this option is non-@code{nil}, then rather than stopping at the +first suffix that exists, @code{load} tests them all, and uses +whichever file is the newest. +@end defopt + @node Library Search @section Library Search @cindex library search @@ -253,37 +278,41 @@ it skips the latter group. in a list of directories specified by the variable @code{load-path}. @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 defvar - 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}: + 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 @example -export EMACSLOADPATH -EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp +"/usr/local/share/emacs/@var{version}/lisp" @end example -@noindent -Here is how to set it from @code{csh}: - -@example -setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/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. + +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. +@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.) @cindex site-lisp directories - If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs -initializes @code{load-path} with the following two directories: +Unless you start Emacs with the @option{--no-site-lisp} option, +it then adds two more @file{site-lisp} directories to the front of +@code{load-path}. These are intended for locally installed Lisp files, +and are normally of the form: @example "/usr/local/share/emacs/@var{version}/site-lisp" @@ -297,26 +326,54 @@ and @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. - - If you run Emacs from the directory where it was built---that is, an -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 +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.) + +@cindex @env{EMACSLOADPATH} environment variable +If the environment variable @env{EMACSLOADPATH} is set, it modifies +the above initialization procedure. Emacs initializes +@code{load-path} based on the value of the environment variable. + +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). +@ignore +@c AFAICS, does not (yet) work right to specify non-absolute elements. +and @samp{.} stands for the current default directory. +@end ignore +Here is an example of how to set @env{EMACSLOADPATH} variable (from a +@command{sh}-style shell): + +@example +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 +@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. +(Another way to modify @code{load-path} is to use the @option{-L} +command-line option when starting Emacs; see below.) + + For each directory in @code{load-path}, Emacs then checks to see if +it contains a file @file{subdirs.el}, and if so, loads it. The +@file{subdirs.el} file is created when Emacs is built/installed, +and contains code that causes Emacs to add any subdirectories of those +directories to @code{load-path}. 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 directories that you specify using the +@option{-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}). @@ -327,12 +384,10 @@ add one or more directories to @code{load-path}. For 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. + 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. @deffn Command locate-library library &optional nosuffix path interactive-call This command finds the precise file name for library @var{library}. It @@ -377,6 +432,8 @@ the shadowed files as a string. @node Loading Non-ASCII @section Loading Non-@acronym{ASCII} Characters +@cindex loading, and non-ASCII characters +@cindex non-ASCII characters in loaded files When Emacs Lisp programs contain string constants with non-@acronym{ASCII} characters, these can be represented within Emacs either as unibyte @@ -412,7 +469,7 @@ Autoloading can also be triggered by looking up the documentation of the function or macro (@pxref{Documentation Basics}). There are two ways to set up an autoloaded function: by calling -@code{autoload}, and by writing a special ``magic'' comment in the +@code{autoload}, and by writing a ``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 @@ -461,7 +518,7 @@ 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 non-void function definition that is not +If @var{function} already has a non-void function definition that is not an autoload object, this function does nothing and returns @code{nil}. Otherwise, it constructs an autoload object (@pxref{Autoload Type}), and stores it as the function definition for @var{function}. The @@ -483,7 +540,7 @@ For 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}), +@file{emacs/etc/DOC} 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 @@ -624,7 +681,7 @@ value of this variable is @code{";;;###autoload"}. @defvar generated-autoload-file The value of this variable names an Emacs Lisp file where the autoload calls should go. The default value is @file{loaddefs.el}, but you can -override that, e.g., in the ``Local Variables'' section of a +override that, e.g., in the local variables section of a @file{.el} file (@pxref{File Local Variables}). The autoload file is assumed to contain a trailer starting with a formfeed character. @end defvar @@ -865,6 +922,8 @@ with a call to @code{provide}. The order of the elements in the @node Where Defined @section Which File Defined a Certain Symbol +@cindex symbol, where defined +@cindex where was a symbol defined @defun symbol-file symbol &optional type This function returns the name of the file that defined @var{symbol}. @@ -910,6 +969,11 @@ The face @var{face} was defined. The feature @var{feature} was required. @item (provide . @var{feature}) The feature @var{feature} was provided. +@item (cl-defmethod @var{method} @var{specializers}) +The named @var{method} was defined by using @code{cl-defmethod}, with +@var{specializers} as its specializers. +@item (define-type . @var{type}) +The type @var{type} was defined. @end table The value of @code{load-history} may have one element whose @sc{car} is @@ -990,19 +1054,18 @@ file that was just loaded. @end defvar If you want code to be executed when a @emph{particular} library is -loaded, use the function @code{eval-after-load}: +loaded, use the macro @code{with-eval-after-load}: -@defun eval-after-load library form -This function arranges to evaluate @var{form} at the end of loading +@defmac with-eval-after-load library body@dots{} +This macro arranges to evaluate @var{body} at the end of loading the file @var{library}, each time @var{library} is loaded. If -@var{library} is already loaded, it evaluates @var{form} right away. -Don't forget to quote @var{form}! +@var{library} is already loaded, it evaluates @var{body} right away. 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 -(eval-after-load "edebug" '(def-edebug-spec c-point t)) +(with-eval-after-load "edebug" (def-edebug-spec c-point t)) @end example To restrict which files can trigger the evaluation, include a @@ -1014,35 +1077,71 @@ example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory @file{my_inst.el}: @example -(eval-after-load "foo/bar/my_inst.elc" @dots{}) +(with-eval-after-load "foo/bar/my_inst.elc" @dots{}) @end example @var{library} can also be a feature (i.e., a symbol), in which case -@var{form} is evaluated at the end of any file where +@var{body} 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}. -@end defun +An error in @var{body} does not undo the load, but does prevent +execution of the rest of @var{body}. +@end defmac Normally, well-designed Lisp programs should not use -@code{eval-after-load}. If you need to examine and set the variables -defined in another library (those meant for outside use), you can do -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}). - -@defvar after-load-alist -This variable stores an alist built by @code{eval-after-load}, -containing the expressions to evaluate when certain libraries are -loaded. Each element looks like this: +@code{with-eval-after-load}. If you need to examine and set the +variables defined in another library (those meant for outside use), +you can do 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}). + +@node Dynamic Modules +@section Emacs Dynamic Modules +@cindex dynamic modules + +@c FIXME: This is intentionally incomplete, as the module integration +@c is not yet finished. To be refined later. + A @dfn{dynamic Emacs module} is a shared library that provides +additional functionality for use in Emacs Lisp programs, just like a +package written in Emacs Lisp would. + + Functions that load Emacs Lisp packages can also load dynamic +modules. They recognize dynamic modules by looking at their file-name +extension, a.k.a.@: ``suffix''. This suffix is platform-dependent. + +@defvar module-file-suffix +This variable holds the system-dependent value of the file-name +extension of the module files. Its value is @file{.so} on Posix hosts +and @file{.dll} on MS-Windows. +@end defvar -@example -(@var{regexp-or-feature} @var{forms}@dots{}) -@end example +@findex emacs_module_init +@vindex plugin_is_GPL_compatible +Every dynamic module should export a C-callable function named +@code{emacs_module_init}, which Emacs will call as part of the call to +@code{load} or @code{require} which loads the module. It should also +export a symbol named @code{plugin_is_GPL_compatible} to indicate that +its code is released under the GPL or compatible license; Emacs will +refuse to load modules that don't export such a symbol. + +If a module needs to call Emacs functions, it should do so through the +API defined and documented in the header file @file{emacs-module.h} +that is part of the Emacs distribution. + +@cindex user-ptr object +Modules can create @code{user-ptr} Lisp objects that embed pointers to +C struct's defined by the module. This is useful for keeping around +complex data structures created by a module, to be passed back to the +module's functions. User-ptr objects can also have associated +@dfn{finalizers} -- functions to be run when the object is GC'ed; this +is useful for freeing any resources allocated for the underlying data +structure, such as memory, open file descriptors, etc. + +@defun user-ptrp object +This function returns @code{t} if its argument is a @code{user-ptr} +object. +@end defun -The key @var{regexp-or-feature} is either a regular expression or a -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 +Loadable modules in Emacs are enabled by using the +@kbd{--with-modules} option at configure time.