X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/7e09ef09a479731d01b1ca46e94ddadd73ac98e3..d6ec146ff9b66a1849932f90f3a5edade28d4579:/doc/lispref/loading.texi diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index cf2f0007ca..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-2015 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,7 +29,15 @@ into a buffer and evaluated there. (Indeed, most code is tested this way.) Most often, the forms are function definitions and variable definitions. -For on-demand loading of external libraries, @pxref{Dynamic Libraries}. + 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. @@ -40,9 +48,10 @@ For on-demand loading of external libraries, @pxref{Dynamic Libraries}. * 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 @@ -64,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 @@ -91,11 +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. +(@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 @@ -193,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 @@ -456,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 @@ -668,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 @@ -956,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 @@ -1071,8 +1089,59 @@ 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}). +@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 + +@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 + +Loadable modules in Emacs are enabled by using the +@kbd{--with-modules} option at configure time.