From: Eli Zaretskii Date: Sat, 5 Dec 2015 11:51:09 +0000 (+0200) Subject: Initial documentation of dynamic modules X-Git-Tag: emacs-25.0.90~537 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=52781882859ded459b97bcc83c8548d8cb67a30f;p=emacs.git Initial documentation of dynamic modules * doc/lispref/loading.texi (Dynamic Modules): New section with initial documentation for dynamic modules. * doc/lispref/elisp.texi (Top): Add "Dynamic Modules" to the detailed menu * etc/NEWS: Fix typos in dynamic modules' entry. --- diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 2d3548f65ba..dedb0a5e40e 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -602,6 +602,7 @@ Loading * 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. Byte Compilation diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 82de765876e..e01f3161731 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -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. @@ -43,6 +51,7 @@ For on-demand loading of external libraries, @pxref{Dynamic Libraries}. * 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 @@ -1076,3 +1085,53 @@ 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. diff --git a/etc/NEWS b/etc/NEWS index ca61fc00ac2..ef2dc1220cc 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -210,7 +210,7 @@ module's functions. User-ptr objects can also have associated "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. A new -predicate `user-ptr-p' returns non-nil if its argument is a `usr-ptr' +predicate `user-ptrp' returns non-nil if its argument is a `user-ptr' object. Loadable modules in Emacs are an experimental feature, and subject to