elisp: Dynamic Modules
15.11 Emacs Dynamic Modules
===========================
A “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.
-- Variable: module-file-suffix
This variable holds the system-dependent value of the file-name
extension of the module files. Its value is ‘.so’ on Posix hosts
and ‘.dll’ on MS-Windows.
Every dynamic module should export a C-callable function named
‘emacs_module_init’, which Emacs will call as part of the call to ‘load’
or ‘require’ which loads the module. It should also export a symbol
named ‘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 ‘emacs-module.h’ that
is part of the Emacs distribution.
Modules can create ‘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
“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.
-- Function: user-ptrp object
This function returns ‘t’ if its argument is a ‘user-ptr’ object.
Loadable modules in Emacs are enabled by using the ‘--with-modules’
option at configure time.