[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] emacs-25 3858b79: Improve documentation of dynamic modules
From: |
Eli Zaretskii |
Subject: |
[Emacs-diffs] emacs-25 3858b79: Improve documentation of dynamic modules |
Date: |
Sat, 21 Nov 2015 10:51:05 +0000 |
branch: emacs-25
commit 3858b7949fdf5af8dd94cefc5a2684ad285e2cdf
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>
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.
---
etc/NEWS | 40 +++++++++++++++++++++++++++++++++-------
src/alloc.c | 2 +-
src/fns.c | 5 +++--
src/lread.c | 22 ++++++++++++----------
4 files changed, 49 insertions(+), 20 deletions(-)
diff --git a/etc/NEWS b/etc/NEWS
index 8ed8133..dce02c3 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -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
diff --git a/src/alloc.c b/src/alloc.c
index 53f9745..ad3f523 100644
--- a/src/alloc.c
+++ b/src/alloc.c
@@ -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)
{
diff --git a/src/fns.c b/src/fns.c
index 029ac6a..824d969 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -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.
diff --git a/src/lread.c b/src/lread.c
index 43100d9..bbff21d 100644
--- a/src/lread.c
+++ b/src/lread.c
@@ -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"),
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] emacs-25 3858b79: Improve documentation of dynamic modules,
Eli Zaretskii <=