Commit 3858b794 authored by Eli Zaretskii's avatar Eli Zaretskii

Improve documentation of dynamic modules

* src/fns.c (Frequire): Doc fix to include the dynamic module
support.
* src/lread.c (Fload, Vload_suffixes): Doc fixes to include the
dynamic module support.
(Fload): Treat the module suffix the same as '*.el' and '*.elc'
wrt the MUST-SUFFIX argument.

* etc/NEWS: Expand documentation of dynamically loaded modules.
parent 22992678
......@@ -305,13 +305,39 @@ header.
which specifies an alternative printing method which is faster when
few or no entries have changed.
** Emacs can now load shared/dynamic libraries (modules) that expose a
C interface. Such modules can provide additional functions or
otherwise interact with Emacs just like Lisp code. Modules have to
export a function `emacs_module_init' and conform to the API laid out
in emacs-module.h. Modules are disabled by default and need to be
enabled using the --with-modules configure flag. They are
experimental and subject to change.
** Emacs can now load shared/dynamic libraries (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. The functions `load' and `require' were
extended to load such modules, as they do with Emacs Lisp packages.
A 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'. Note
that any module that provides Lisp-callable functions will have to use
Emacs functions such as `fset' and `funcall', in order to register its
functions with the Emacs Lisp interpreter.
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. A new
predicate `user-ptr-p' returns non-nil if its argument is a `usr-ptr'
object.
Loadable modules in Emacs are an experimental feature, and subject to
change in future releases. For that reason, their support is disabled
by default, and must be enabled by using the `--with-modules' option
at configure time.
* Editing Changes in Emacs 25.1
......
......@@ -3712,7 +3712,7 @@ make_event_array (ptrdiff_t nargs, Lisp_Object *args)
}
#ifdef HAVE_MODULES
/* Create a new module user ptr object. */
/* Create a new module user ptr object. */
Lisp_Object
make_user_ptr (void (*finalizer) (void*), void *p)
{
......
......@@ -2764,8 +2764,9 @@ DEFUN ("require", Frequire, Srequire, 1, 3, 0,
If FEATURE is not a member of the list `features', then the feature
is not loaded; so load the file FILENAME.
If FILENAME is omitted, the printname of FEATURE is used as the file name,
and `load' will try to load this name appended with the suffix `.elc' or
`.el', in that order. The name without appended suffix will not be used.
and `load' will try to load this name appended with the suffix `.elc',
`.el', or the system-dependent suffix for dynamic module files, in that
order. The name without appended suffix will not be used.
See `get-load-suffixes' for the complete list of suffixes.
If the optional third argument NOERROR is non-nil,
then return nil if the file is not found instead of signaling an error.
......
......@@ -987,7 +987,8 @@ suffix_p (Lisp_Object string, const char *suffix)
DEFUN ("load", Fload, Sload, 1, 5, 0,
doc: /* Execute a file of Lisp code named FILE.
First try FILE with `.elc' appended, then try with `.el',
First try FILE with `.elc' appended, then try with `.el', then try
with a system-dependent suffix of dynamic modules (see `load-suffixes'),
then try FILE unmodified (the exact suffixes in the exact order are
determined by `load-suffixes'). Environment variable references in
FILE are replaced with their values by calling `substitute-in-file-name'.
......@@ -999,10 +1000,10 @@ Print messages at start and end of loading unless
optional third arg NOMESSAGE is non-nil (but `force-load-messages'
overrides that).
If optional fourth arg NOSUFFIX is non-nil, don't try adding
suffixes `.elc' or `.el' to the specified name FILE.
suffixes to the specified name FILE.
If optional fifth arg MUST-SUFFIX is non-nil, insist on
the suffix `.elc' or `.el'; don't accept just FILE unless
it ends in one of those suffixes or includes a directory name.
the suffix `.elc' or `.el' or the module suffix; don't accept just
FILE unless it ends in one of those suffixes or includes a directory name.
If NOSUFFIX is nil, then if a file could not be found, try looking for
a different representation of the file by adding non-empty suffixes to
......@@ -1084,7 +1085,9 @@ Return t if the file exists and loads successfully. */)
if (! NILP (must_suffix))
{
/* Don't insist on adding a suffix if FILE already ends with one. */
if (suffix_p (file, ".el") || suffix_p (file, ".elc"))
if (suffix_p (file, ".el")
|| suffix_p (file, ".elc")
|| suffix_p (file, MODULES_SUFFIX))
must_suffix = Qnil;
/* Don't insist on adding a suffix
if the argument includes a directory name. */
......@@ -1158,9 +1161,7 @@ Return t if the file exists and loads successfully. */)
#ifdef HAVE_MODULES
if (suffix_p (found, MODULES_SUFFIX))
{
return Fmodule_load (found);
}
return Fmodule_load (found);
#endif
/* Check if we're stuck in a recursive load cycle.
......@@ -4498,10 +4499,11 @@ programs that process this list should tolerate directories both with
and without trailing slashes. */);
DEFVAR_LISP ("load-suffixes", Vload_suffixes,
doc: /* List of suffixes for (compiled or source) Emacs Lisp files.
doc: /* List of suffixes for Emacs Lisp files and dynamic modules.
This list includes suffixes for both compiled and source Emacs Lisp files.
This list should not include the empty string.
`load' and related functions try to append these suffixes, in order,
to the specified file name if a Lisp suffix is allowed or required. */);
to the specified file name if a suffix is allowed or required. */);
#ifdef HAVE_MODULES
Vload_suffixes = list3 (build_pure_c_string (".elc"),
build_pure_c_string (".el"),
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment